{extend name="layout" /}

{block name="title"}
<title>过滤器 数据筛选 - thinkPHP极速后台开发</title>
<meta name="title" content="过滤器 数据筛选 - thinkPHP极速后台开发">
<meta name="keywords" content="过滤器 数据筛选,php,后台开发包，thinkphp、easyadmin、admin,easy,thinkeasyadmin">
<meta name="description" content="配置过滤器,快速筛选列表页面的数据;easyadmin灵活可定制的thinkphp的后台开发工具包,助你快速开发后台">
{/block}

{block name="main"}

<ul class="right-menu">
    <li><a href="#default" class="active">默认过滤器</a></li>
    <li><a href="#create">创建过滤器</a></li>
    <li><a href="#join">join</a></li>
    <li><a href="#param">参数说明</a></li>
    <li><a href="#custom_query">自定义查询</a></li>
    <li><a href="#highlight">搜索结果高亮</a></li>
    <li><a href="#select">下拉选择类型的搜索</a></li>
    <li><a href="#datetime">日期范围搜索</a></li>
    <li><a href="{:url('list_field')}">更多搜索类型</a></li>
</ul>


<fieldset id="liseField" class="layui-elem-field">
    <legend>过滤器</legend>
    <div class="layui-field-box">


        <fieldset class="layui-elem-field layui-field-title" id="default">
            <legend>默认过滤器</legend>
            <div class="layui-field-box">
                <p>默认会创建一个全部字段的搜索框, 点击搜索时, <code>like</code>查询<code>全部字段</code></p>

                <img src="/doc_img/default_filter.png" alt="默认搜索框">
            </div>
        </fieldset>


        <fieldset class="layui-elem-field layui-field-title" id="create">
            <legend>创建过滤器</legend>
            <div class="layui-field-box">
                <p>创建过滤器只需要重写<code>configListFilter</code>方法:</code></p>

                <pre class="php">
#project\app\admin\controller\Category.php

namespace app\admin\controller;

use easyadmin\app\libs\ListFilter;

class Category extends \easyadmin\controller\Admin
{
    protected function configListFilter(ListFilter $filter)
    {
        $filter->addFilter('name', '名称', FormText::class);
    }
}

</pre>
            </div>
        </fieldset>


        <fieldset class="layui-elem-field layui-field-title" id="join">
            <legend>过滤器 join</legend>
            <div class="layui-field-box">
                <p>过滤器使用 join 同 <a href="{:url('lists_join')}">列表的join</a> 一样, 先调用<code>configListJoin</code>方法,记住声明的别名,然后什么过滤器字段的时候使用相同的别名即可;
                </p>

                <pre class="php" >
#project\app\admin\controller\Category.php

namespace app\admin\controller;

use easyadmin\app\libs\Page;
use easyadmin\app\columns\form\FormText;
use easyadmin\app\libs\ListFilter;
use think\db\Query;

class Category extends \easyadmin\controller\Admin
{

    protected function configListFilter(ListFilter $filter)
    {
        // configListJoin 方法类的别名, 如果是查询的主表, 可不写别名
        $filter->addFilter('c.name', '名称', FormText::class);
    }

    /**
     * 配置关联查询
     * @param Query $query  thinkphp 的 query, 可使用 thinkphp 的数据库查询方法, 这里主要是join 关联数据表
     * @param string $alias 查询主表的别名
     */
    protected function configListJoin(Page $page, Query $query, string $alias)
    {
        // 这里就是 thinkphp 的join用法, 详细可参考 thinkphp 的文档
        // 这里关联 category 表使用的别名是 c ,在列表字段,过滤器字段 同样使用 c 别名即可
        $query->join('category c','c.id='. $alias .'.parent_id');
    }

}

</pre>
            </div>
        </fieldset>

        <fieldset class="layui-elem-field layui-field-title" id="param">
            <legend>addFilter 方法 参数说明:</legend>
            <div class="layui-field-box">
                <table class="layui-table">
                    <thead>
                    <tr>
                        <th>字段</th>
                        <th>说明</th>
                        <th>类型</th>
                        <th>必填</th>
                        <th>默认值</th>
                    </tr>
                    </thead>
                    <tbody>
                    <tr>
                        <td>field</td>
                        <td>字段名称;数据库表的字段,例如:<code>name</code>; 如果是<a href="{:url('lists_join')}#join">多表关联查询</a>
                            ,需要写上关联表的别名,例如:<code>user.name</code> ;
                        </td>
                        <td>string</td>
                        <td>是</td>
                        <td></td>
                    </tr>
                    <tr>
                        <td>label</td>
                        <td>字段标题,显示名称</td>
                        <td>string</td>
                        <td>是</td>
                        <td></td>
                    </tr>
                    <tr>
                        <td>fieldClass</td>
                        <td>渲染字段的类名; 例如是使用 ListText 类渲染本字段,则填写 ListText::class ; <a
                                href="{:url('fields')}#liseFieldAll">详见预定义字段</a>
                        </td>
                        <td>string</td>
                        <td>是</td>
                        <td></td>
                    </tr>
                    <tr>
                        <td>options</td>
                        <td>字段的选项; 不同的字段有不同的选项, <a href="{:url('fields')}#liseFieldAll">详见预定义字段</a></td>
                        <td>array</td>
                        <td>否</td>
                        <td></td>
                    </tr>
                    </tbody>
                </table>
            </div>
        </fieldset>


        <fieldset class="layui-elem-field layui-field-title" id="custom_query">
            <legend>自定义查询</legend>
            <div class="layui-field-box">
                <p>自定义查询,字需要在<code>options</code>中传入<code>filter_callback</code>参数:</p>

                <pre class="php">
#project\app\admin\controller\Category.php

namespace app\admin\controller;

use easyadmin\app\libs\ListFilter;
use think\db\Query;

class Category extends \easyadmin\controller\Admin
{
    protected function configListFilter(ListFilter $filter)
    {
        $filter->addFilter('name', '名称', FormText::class, [
            /**
             * @param Query $query thinkphp 的查询 query 对象, 可用 thinkphp 的任意查询方法
             * @param string $alias 主表的查询别名,  如果是join的字段, 不要用这个别名,直接用 join 声明的别名
             * @param void $val 用户输入框输入的值
             */
            'filter_callback' => function (Query $query, $alias, $val) {
                //根据自己的业务,判断是否需要空值判断
                if(!empty($val)){
                     {literal}$query->where("{$alias}.name", 'like', "%{$val}%"); {/literal}
                }
            }
        ]);
    }
}
</pre>
            </div>
        </fieldset>


        <fieldset class="layui-elem-field layui-field-title">
            <legend>filter_callback 方法 参数说明:</legend>
            <div class="layui-field-box">
                <table class="layui-table">
                    <thead>
                    <tr>
                        <th>字段</th>
                        <th>说明</th>
                        <th>类型</th>
                        <th>必填</th>
                        <th>默认值</th>
                    </tr>
                    </thead>
                    <tbody>
                    <tr>
                        <td>query</td>
                        <td><code>thinkphp</code> 的数据库查询对象, 可用任何<code>thinkphp</code>的查询方法</td>
                        <td>Query Object</td>
                        <td>是</td>
                        <td></td>
                    </tr>
                    <tr>
                        <td>alias</td>
                        <td>查询主表的别名 select * from table as <code>table_name</code> 中的 <code>table_name</code></td>
                        <td>string</td>
                        <td>是</td>
                        <td></td>
                    </tr>
                    <tr>
                        <td>val</td>
                        <td>当前用户输入的值</td>
                        <td>string</td>
                        <td>是</td>
                        <td></td>
                    </tr>
                    </tbody>
                </table>
            </div>
        </fieldset>


        <fieldset class="layui-elem-field layui-field-title" id="highlight">
            <legend>搜索结果高亮</legend>
            <div class="layui-field-box">
                <p>顾名思义,就是用户输入的值,如果在结果中出现,就高亮显示它</p>
                <img src="/doc_img/default_filter.png" alt="默认搜索框">
                <p>搜索结果高亮,字需要在<code>options</code>中传入<code>highlight</code>参数:</p>
                <p>不过只有部分字段支持,列表是<code>FormText</code>这种文本类型的就支持, 列表是 select checkbox switch 这种就不支持了 </p>

                <pre class="php">
#project\app\admin\controller\Category.php

namespace app\admin\controller;

use easyadmin\app\libs\ListFilter;

class Category extends \easyadmin\controller\Admin
{
    protected function configListFilter(ListFilter $filter)
    {
        $filter->addFilter('name', '名称', FormText::class, [

            //高亮方式有3种, 默认第一种 ;

            // true 开启高亮, false 关闭高亮
            'highlight' => true,

            //自定义一种颜色值  red blue #f3f ... 等等正确的颜色值都可用,
            'highlight' => 'red',

            // 回调函数处理高亮, 传入用户输入的值
            'highlight' => function ($val) {
                return '<span style="color: #00cc00">' . $val . '</span>';
            },

            // false: 列表中所有包含输入框值的都高亮, 高亮全部字段
            // true: 只是搜索字段对应的列表字段高亮,  高亮一个字段
            'highlight_self'=>false ,
        ]);
    }
}
</pre>

                <p><code>highlight</code> 可用值</p>
                <table class="layui-table">
                    <thead>
                    <tr>
                        <th>值</th>
                        <th>说明</th>
                    </tr>
                    </thead>
                    <tbody>
                    <tr>
                        <td>false</td>
                        <td>关闭高亮</td>
                    </tr>
                    <tr>
                        <td>true</td>
                        <td>默认的高亮, 黄色背景 白色文字</td>
                    </tr>
                    <tr>
                        <td>颜色值</td>
                        <td>直接用指定的颜色显示</td>
                    </tr>
                    <tr>
                        <td>匿名函数</td>
                        <td>自定义函数处理</td>
                    </tr>
                    </tbody>
                </table>

                <p>默认是列表中所有字段都高亮的, 如果仅仅是需要高亮搜索字段,可指定<code>highlight_self</code>为<code>true</code></p>

            </div>
        </fieldset>


        <fieldset class="layui-elem-field layui-field-title" id="select">
            <legend>下拉选择类型的搜索</legend>
            <div class="layui-field-box">
                <pre class="php">
#project\app\admin\controller\Category.php

namespace app\admin\controller;

use easyadmin\app\libs\ListFilter;
use easyadmin\app\columns\form\FormSelect;

class Category extends \easyadmin\controller\Admin
{
    protected function configListFilter(ListFilter $filter)
    {
        $filter->addFilter('name', '名称', FormSelect::class, [
            'highlight'=>true,  //是否启用搜索结果高亮
            'options' => [      //下拉选择列表
                ['key'=>'php','text'=>'PHP'],
                ['key'=>'javascript','text'=>'js'],
            ]
        ]);
    }
}
</pre>
                <img src="/doc_img/select_filter.png" alt="下拉选择类型的搜索">
            </div>
        </fieldset>


        <fieldset class="layui-elem-field layui-field-title" id="datetime">
            <legend>日期范围搜索</legend>
            <div class="layui-field-box">
                <p>展示一个 日期范围选择框,默认用<code>BETWEEN AND</code>搜索; 需要自定义搜索方式,参考<a href="#custom_filter_query">自定义查询</a></p>
                <pre class="php">
#project\app\admin\controller\Category.php

namespace app\admin\controller;

use easyadmin\app\libs\ListFilter;
use easyadmin\app\columns\form\FormDateTimeRange;

class Category extends \easyadmin\controller\Admin
{
    protected function configListFilter(ListFilter $filter)
    {
        $filter->addFilter('time', '创建时间', FormDateTimeRange::class, [
            'in_format' => function ($val) {  //处理用户输入值的回调, 通常和 format 成对出现
                return strtotime($val);
            },
            'format' => function ($val) {     //处理完的值用什么样的格式输出到界面上, 通常和  in_format 成对出现
                return date('Y-m-d H:i:s',$val);
            }
        ]);
    }
}
</pre>
                <img src="/doc_img/datetime_range_filter.png" alt="下拉选择类型的搜索">
            </div>
        </fieldset>

    </div>

    <h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;更多字段类型, <a href="{:url('form_field')}#liseFieldAll">详见预定义字段</a></h3>
    <br><br><br>

</fieldset>


{/block}


